home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DCamera.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-08-17  |  11.0 KB  |  386 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        QD3DCamera.h
  3.  
  4.      Contains:    Generic camera routines                                             
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.5.4
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1995-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __QD3DCAMERA__
  18. #define __QD3DCAMERA__
  19.  
  20. #ifndef __QD3D__
  21. #include <QD3D.h>
  22. #endif
  23.  
  24.  
  25.  
  26. #if PRAGMA_ONCE
  27. #pragma once
  28. #endif
  29.  
  30. #ifdef __cplusplus
  31. extern "C" {
  32. #endif
  33.  
  34. #if PRAGMA_IMPORT
  35. #pragma import on
  36. #endif
  37.  
  38. #if PRAGMA_STRUCT_ALIGN
  39.     #pragma options align=power
  40. #elif PRAGMA_STRUCT_PACKPUSH
  41.     #pragma pack(push, 2)
  42. #elif PRAGMA_STRUCT_PACK
  43.     #pragma pack(2)
  44. #endif
  45.  
  46. #if PRAGMA_ENUM_ALWAYSINT
  47.     #pragma enumsalwaysint on
  48. #elif PRAGMA_ENUM_OPTIONS
  49.     #pragma option enum=int
  50. #elif PRAGMA_ENUM_PACK
  51.     #if __option(pack_enums)
  52.         #define PRAGMA_ENUM_PACK__QD3DCAMERA__
  53.     #endif
  54.     #pragma options(!pack_enums)
  55. #endif
  56.  
  57. /******************************************************************************
  58.  **                                                                             **
  59.  **                            Data Structure Definitions                         **
  60.  **                                                                             **
  61.  *****************************************************************************/
  62. /*
  63.  *  The placement of the camera.
  64.  */
  65.  
  66. struct TQ3CameraPlacement {
  67.     TQ3Point3D                         cameraLocation;                /*  Location point of the camera     */
  68.     TQ3Point3D                         pointOfInterest;            /*  Point of interest                 */
  69.     TQ3Vector3D                     upVector;                    /*  "up" vector                     */
  70. };
  71. typedef struct TQ3CameraPlacement        TQ3CameraPlacement;
  72. /*
  73.  *  The range of the camera.
  74.  */
  75.  
  76. struct TQ3CameraRange {
  77.     float                             hither;                        /*  Hither plane, measured from "from" towards "to"    */
  78.     float                             yon;                        /*  Yon  plane, measured from "from" towards "to"     */
  79. };
  80. typedef struct TQ3CameraRange            TQ3CameraRange;
  81. /*
  82.  *  Viewport specification.  Origin is (-1, 1), and corresponds to the 
  83.  *  upper left-hand corner; width and height maximum is (2.0, 2.0),
  84.  *  corresponding to the lower left-hand corner of the window.  The
  85.  *  TQ3Viewport specifies a part of the viewPlane that gets displayed 
  86.  *    on the window that is to be drawn.
  87.  *  Normally, it is set with an origin of (-1.0, 1.0), and a width and
  88.  *  height of both 2.0, specifying that the entire window is to be
  89.  *  drawn.  If, for example, an exposure event of the window exposed
  90.  *  the right half of the window, you would set the origin to (0, 1),
  91.  *  and the width and height to (1.0) and (2.0), respectively.
  92.  *
  93.  */
  94.  
  95. struct TQ3CameraViewPort {
  96.     TQ3Point2D                         origin;
  97.     float                             width;
  98.     float                             height;
  99. };
  100. typedef struct TQ3CameraViewPort        TQ3CameraViewPort;
  101.  
  102. struct TQ3CameraData {
  103.     TQ3CameraPlacement                 placement;
  104.     TQ3CameraRange                     range;
  105.     TQ3CameraViewPort                 viewPort;
  106. };
  107. typedef struct TQ3CameraData            TQ3CameraData;
  108. /*
  109.  *  An orthographic camera.
  110.  *
  111.  *  The lens characteristics are set with the dimensions of a
  112.  *  rectangular viewPort in the frame of the camera.
  113.  */
  114.  
  115. struct TQ3OrthographicCameraData {
  116.     TQ3CameraData                     cameraData;
  117.     float                             left;
  118.     float                             top;
  119.     float                             right;
  120.     float                             bottom;
  121. };
  122. typedef struct TQ3OrthographicCameraData TQ3OrthographicCameraData;
  123. /*
  124.  *  A perspective camera specified in terms of an arbitrary view plane.
  125.  *
  126.  *  This is most useful when setting the camera to look at a particular
  127.  *  object.  The viewPlane is set to distance from the camera to the object.
  128.  *  The halfWidth is set to half the width of the cross section of the object,
  129.  *  and the halfHeight equal to the halfWidth divided by the aspect ratio
  130.  *  of the viewPort.
  131.  * 
  132.  *  This is the only perspective camera with specifications for off-axis
  133.  *  viewing, which is desirable for scrolling.
  134.  */
  135.  
  136. struct TQ3ViewPlaneCameraData {
  137.     TQ3CameraData                     cameraData;
  138.     float                             viewPlane;
  139.     float                             halfWidthAtViewPlane;
  140.     float                             halfHeightAtViewPlane;
  141.     float                             centerXOnViewPlane;
  142.     float                             centerYOnViewPlane;
  143. };
  144. typedef struct TQ3ViewPlaneCameraData    TQ3ViewPlaneCameraData;
  145. /*
  146.  *    A view angle aspect camera is a perspective camera specified in 
  147.  *    terms of the minimum view angle and the aspect ratio of X to Y.
  148.  *
  149.  */
  150.  
  151. struct TQ3ViewAngleAspectCameraData {
  152.     TQ3CameraData                     cameraData;
  153.     float                             fov;
  154.     float                             aspectRatioXToY;
  155. };
  156. typedef struct TQ3ViewAngleAspectCameraData TQ3ViewAngleAspectCameraData;
  157. /******************************************************************************
  158.  **                                                                             **
  159.  **                            Generic Camera routines                             **
  160.  **                                                                             **
  161.  *****************************************************************************/
  162.  
  163. EXTERN_API_C( TQ3ObjectType )
  164. Q3Camera_GetType                (TQ3CameraObject         camera);
  165.  
  166. EXTERN_API_C( TQ3Status )
  167. Q3Camera_SetData                (TQ3CameraObject         camera,
  168.                                  const TQ3CameraData *    cameraData);
  169.  
  170. EXTERN_API_C( TQ3Status )
  171. Q3Camera_GetData                (TQ3CameraObject         camera,
  172.                                  TQ3CameraData *        cameraData);
  173.  
  174. EXTERN_API_C( TQ3Status )
  175. Q3Camera_SetPlacement            (TQ3CameraObject         camera,
  176.                                  const TQ3CameraPlacement * placement);
  177.  
  178. EXTERN_API_C( TQ3Status )
  179. Q3Camera_GetPlacement            (TQ3CameraObject         camera,
  180.                                  TQ3CameraPlacement *    placement);
  181.  
  182. EXTERN_API_C( TQ3Status )
  183. Q3Camera_SetRange                (TQ3CameraObject         camera,
  184.                                  const TQ3CameraRange *    range);
  185.  
  186. EXTERN_API_C( TQ3Status )
  187. Q3Camera_GetRange                (TQ3CameraObject         camera,
  188.                                  TQ3CameraRange *        range);
  189.  
  190. EXTERN_API_C( TQ3Status )
  191. Q3Camera_SetViewPort            (TQ3CameraObject         camera,
  192.                                  const TQ3CameraViewPort * viewPort);
  193.  
  194. EXTERN_API_C( TQ3Status )
  195. Q3Camera_GetViewPort            (TQ3CameraObject         camera,
  196.                                  TQ3CameraViewPort *    viewPort);
  197.  
  198. EXTERN_API_C( TQ3Status )
  199. Q3Camera_GetWorldToView            (TQ3CameraObject         camera,
  200.                                  TQ3Matrix4x4 *            worldToView);
  201.  
  202. EXTERN_API_C( TQ3Status )
  203. Q3Camera_GetWorldToFrustum        (TQ3CameraObject         camera,
  204.                                  TQ3Matrix4x4 *            worldToFrustum);
  205.  
  206. EXTERN_API_C( TQ3Status )
  207. Q3Camera_GetViewToFrustum        (TQ3CameraObject         camera,
  208.                                  TQ3Matrix4x4 *            viewToFrustum);
  209.  
  210.  
  211. /******************************************************************************
  212.  **                                                                             **
  213.  **                            Specific Camera Routines                          **
  214.  **                                                                             **
  215.  *****************************************************************************/
  216. /******************************************************************************
  217.  **                                                                             **
  218.  **                            Orthographic Camera                                  **
  219.  **                                                                             **
  220.  *****************************************************************************/
  221. EXTERN_API_C( TQ3CameraObject )
  222. Q3OrthographicCamera_New        (const TQ3OrthographicCameraData * orthographicData);
  223.  
  224. EXTERN_API_C( TQ3Status )
  225. Q3OrthographicCamera_GetData    (TQ3CameraObject         camera,
  226.                                  TQ3OrthographicCameraData * cameraData);
  227.  
  228. EXTERN_API_C( TQ3Status )
  229. Q3OrthographicCamera_SetData    (TQ3CameraObject         camera,
  230.                                  const TQ3OrthographicCameraData * cameraData);
  231.  
  232. EXTERN_API_C( TQ3Status )
  233. Q3OrthographicCamera_SetLeft    (TQ3CameraObject         camera,
  234.                                  float                     left);
  235.  
  236. EXTERN_API_C( TQ3Status )
  237. Q3OrthographicCamera_GetLeft    (TQ3CameraObject         camera,
  238.                                  float *                left);
  239.  
  240. EXTERN_API_C( TQ3Status )
  241. Q3OrthographicCamera_SetTop        (TQ3CameraObject         camera,
  242.                                  float                     top);
  243.  
  244. EXTERN_API_C( TQ3Status )
  245. Q3OrthographicCamera_GetTop        (TQ3CameraObject         camera,
  246.                                  float *                top);
  247.  
  248. EXTERN_API_C( TQ3Status )
  249. Q3OrthographicCamera_SetRight    (TQ3CameraObject         camera,
  250.                                  float                     right);
  251.  
  252. EXTERN_API_C( TQ3Status )
  253. Q3OrthographicCamera_GetRight    (TQ3CameraObject         camera,
  254.                                  float *                right);
  255.  
  256. EXTERN_API_C( TQ3Status )
  257. Q3OrthographicCamera_SetBottom    (TQ3CameraObject         camera,
  258.                                  float                     bottom);
  259.  
  260. EXTERN_API_C( TQ3Status )
  261. Q3OrthographicCamera_GetBottom    (TQ3CameraObject         camera,
  262.                                  float *                bottom);
  263.  
  264.  
  265. /******************************************************************************
  266.  **                                                                             **
  267.  **                            ViewPlane Camera                                  **
  268.  **                                                                             **
  269.  *****************************************************************************/
  270. EXTERN_API_C( TQ3CameraObject )
  271. Q3ViewPlaneCamera_New            (const TQ3ViewPlaneCameraData * cameraData);
  272.  
  273. EXTERN_API_C( TQ3Status )
  274. Q3ViewPlaneCamera_GetData        (TQ3CameraObject         camera,
  275.                                  TQ3ViewPlaneCameraData * cameraData);
  276.  
  277. EXTERN_API_C( TQ3Status )
  278. Q3ViewPlaneCamera_SetData        (TQ3CameraObject         camera,
  279.                                  const TQ3ViewPlaneCameraData * cameraData);
  280.  
  281. EXTERN_API_C( TQ3Status )
  282. Q3ViewPlaneCamera_SetViewPlane    (TQ3CameraObject         camera,
  283.                                  float                     viewPlane);
  284.  
  285. EXTERN_API_C( TQ3Status )
  286. Q3ViewPlaneCamera_GetViewPlane    (TQ3CameraObject         camera,
  287.                                  float *                viewPlane);
  288.  
  289. EXTERN_API_C( TQ3Status )
  290. Q3ViewPlaneCamera_SetHalfWidth    (TQ3CameraObject         camera,
  291.                                  float                     halfWidthAtViewPlane);
  292.  
  293. EXTERN_API_C( TQ3Status )
  294. Q3ViewPlaneCamera_GetHalfWidth    (TQ3CameraObject         camera,
  295.                                  float *                halfWidthAtViewPlane);
  296.  
  297. EXTERN_API_C( TQ3Status )
  298. Q3ViewPlaneCamera_SetHalfHeight    (TQ3CameraObject         camera,
  299.                                  float                     halfHeightAtViewPlane);
  300.  
  301. EXTERN_API_C( TQ3Status )
  302. Q3ViewPlaneCamera_GetHalfHeight    (TQ3CameraObject         camera,
  303.                                  float *                halfHeightAtViewPlane);
  304.  
  305. EXTERN_API_C( TQ3Status )
  306. Q3ViewPlaneCamera_SetCenterX    (TQ3CameraObject         camera,
  307.                                  float                     centerXOnViewPlane);
  308.  
  309. EXTERN_API_C( TQ3Status )
  310. Q3ViewPlaneCamera_GetCenterX    (TQ3CameraObject         camera,
  311.                                  float *                centerXOnViewPlane);
  312.  
  313. EXTERN_API_C( TQ3Status )
  314. Q3ViewPlaneCamera_SetCenterY    (TQ3CameraObject         camera,
  315.                                  float                     centerYOnViewPlane);
  316.  
  317. EXTERN_API_C( TQ3Status )
  318. Q3ViewPlaneCamera_GetCenterY    (TQ3CameraObject         camera,
  319.                                  float *                centerYOnViewPlane);
  320.  
  321.  
  322. /******************************************************************************
  323.  **                                                                             **
  324.  **                            View Angle Aspect Camera                          **
  325.  **                                                                             **
  326.  *****************************************************************************/
  327. EXTERN_API_C( TQ3CameraObject )
  328. Q3ViewAngleAspectCamera_New        (const TQ3ViewAngleAspectCameraData * cameraData);
  329.  
  330. EXTERN_API_C( TQ3Status )
  331. Q3ViewAngleAspectCamera_SetData    (TQ3CameraObject         camera,
  332.                                  const TQ3ViewAngleAspectCameraData * cameraData);
  333.  
  334. EXTERN_API_C( TQ3Status )
  335. Q3ViewAngleAspectCamera_GetData    (TQ3CameraObject         camera,
  336.                                  TQ3ViewAngleAspectCameraData * cameraData);
  337.  
  338. EXTERN_API_C( TQ3Status )
  339. Q3ViewAngleAspectCamera_SetFOV    (TQ3CameraObject         camera,
  340.                                  float                     fov);
  341.  
  342. EXTERN_API_C( TQ3Status )
  343. Q3ViewAngleAspectCamera_GetFOV    (TQ3CameraObject         camera,
  344.                                  float *                fov);
  345.  
  346. EXTERN_API_C( TQ3Status )
  347. Q3ViewAngleAspectCamera_SetAspectRatio (TQ3CameraObject  camera,
  348.                                  float                     aspectRatioXToY);
  349.  
  350. EXTERN_API_C( TQ3Status )
  351. Q3ViewAngleAspectCamera_GetAspectRatio (TQ3CameraObject  camera,
  352.                                  float *                aspectRatioXToY);
  353.  
  354.  
  355.  
  356.  
  357.  
  358. #if PRAGMA_ENUM_ALWAYSINT
  359.     #pragma enumsalwaysint reset
  360. #elif PRAGMA_ENUM_OPTIONS
  361.     #pragma option enum=reset
  362. #elif defined(PRAGMA_ENUM_PACK__QD3DCAMERA__)
  363.     #pragma options(pack_enums)
  364. #endif
  365.  
  366. #if PRAGMA_STRUCT_ALIGN
  367.     #pragma options align=reset
  368. #elif PRAGMA_STRUCT_PACKPUSH
  369.     #pragma pack(pop)
  370. #elif PRAGMA_STRUCT_PACK
  371.     #pragma pack()
  372. #endif
  373.  
  374. #ifdef PRAGMA_IMPORT_OFF
  375. #pragma import off
  376. #elif PRAGMA_IMPORT
  377. #pragma import reset
  378. #endif
  379.  
  380. #ifdef __cplusplus
  381. }
  382. #endif
  383.  
  384. #endif /* __QD3DCAMERA__ */
  385.  
  386.